home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / SetResult.3 < prev    next >
Encoding:
Text File  |  1994-12-17  |  5.9 KB  |  150 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) SetResult.3 1.13 94/12/17 16:17:30
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_SetResult tclc 7.0
  12. .BS
  13. .SH NAME
  14. Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. \fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
  20. .sp
  21. \fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
  22. .sp
  23. .VS
  24. \fBTcl_AppendElement\fR(\fIinterp, string\fR)
  25. .VE
  26. .sp
  27. \fBTcl_ResetResult\fR(\fIinterp\fR)
  28. .sp
  29. \fBTcl_FreeResult\fR(\fIinterp\fR)
  30. .SH ARGUMENTS
  31. .AS Tcl_FreeProc freeProc
  32. .AP Tcl_Interp *interp out
  33. Interpreter whose result is to be modified.
  34. .AP char *string in
  35. String value to become result for \fIinterp\fR or to be
  36. appended to existing result.
  37. .AP Tcl_FreeProc freeProc in
  38. Address of procedure to call to release storage at
  39. \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
  40. \fBTCL_VOLATILE\fR.
  41. .BE
  42.  
  43. .SH DESCRIPTION
  44. .PP
  45. The procedures described here are utilities for setting the
  46. result/error string in a Tcl interpreter.
  47. .PP
  48. \fBTcl_SetResult\fR
  49. arranges for \fIstring\fR to be the return string for the current Tcl
  50. command in \fIinterp\fR, replacing any existing result.
  51. If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
  52. refers to an area of static storage that is guaranteed not to be
  53. modified until at least the next call to \fBTcl_Eval\fR.
  54. If \fIfreeProc\fR
  55. is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
  56. to \fBmalloc()\fR and is now the property of the Tcl system.
  57. \fBTcl_SetResult\fR will arrange for the string's storage to be
  58. released by calling \fBfree()\fR when it is no longer needed.
  59. If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
  60. points to an area of memory that is likely to be overwritten when
  61. \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
  62. In this case \fBTcl_SetResult\fR will make a copy of the string in
  63. dynamically allocated storage and arrange for the copy to be the
  64. return string for the current Tcl command.
  65. .PP
  66. If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
  67. \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
  68. of a procedure that Tcl should call to free the string.
  69. This allows applications to use non-standard storage allocators.
  70. When Tcl no longer needs the storage for the string, it will
  71. call \fIfreeProc\fR.  \fIFreeProc\fR should have arguments and
  72. result that match the type \fBTcl_FreeProc\fR:
  73. .nf
  74. .RS
  75.  
  76. typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
  77.  
  78. .RE
  79. .fi
  80. When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
  81. the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
  82. .PP
  83. If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
  84. and \fBTcl_SetResult\fR
  85. re-initializes \fIinterp\fR's result to point to the pre-allocated result
  86. area, with an empty string in the result area.
  87. .PP
  88. If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
  89. result, \fBTcl_SetResult\fR does whatever is necessary to dispose
  90. of the old result (see the \fBTcl_Interp\fR manual entry for details
  91. on this).
  92. .PP
  93. \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
  94. It takes each of its \fIstring\fR arguments and appends them in order
  95. to the current result associated with \fIinterp\fR.
  96. If the result is in its initialized empty state (e.g. a command procedure
  97. was just invoked or \fBTcl_ResetResult\fR was just called),
  98. then \fBTcl_AppendResult\fR sets the result to the concatenation of
  99. its \fIstring\fR arguments.
  100. \fBTcl_AppendResult\fR may be called repeatedly as additional pieces
  101. of the result are produced.
  102. \fBTcl_AppendResult\fR takes care of all the
  103. storage management issues associated with managing \fIinterp\fR's
  104. result, such as allocating a larger result area if necessary.
  105. Any number of \fIstring\fR arguments may be passed in a single
  106. call;  the last argument in the list must be a NULL pointer.
  107. .PP
  108. \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
  109. that it allows results to be built up in pieces.
  110. However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
  111. argument and it appends that argument to the current result
  112. as a proper Tcl list element.
  113. \fBTcl_AppendElement\fR adds backslashes or braces if necessary
  114. to ensure that \fIinterp\fR's result can be parsed as a list and that
  115. \fIstring\fR will be extracted as a single element.
  116. Under normal conditions, \fBTcl_AppendElement\fR will add a space
  117. character to \fIinterp\fR's result just before adding the new
  118. list element, so that the list elements in the result are properly
  119. separated.
  120. .VS
  121. However if the new list element is the first in a list or sub-list
  122. (i.e. \fIinterp\fR's current result is empty, or consists of the
  123. single character ``{'', or ends in the characters `` {'') then no
  124. space is added.
  125. .VE
  126. .PP
  127. \fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
  128. freeing the memory associated with it if the current result was
  129. dynamically allocated.
  130. It leaves the result in its normal initialized state with
  131. \fIinterp->result\fR pointing to a static buffer containing
  132. \fBTCL_RESULT_SIZE\fR characters, of which the first character
  133. is zero.
  134. \fBTcl_ResetResult\fR also clears the error state managed by
  135. \fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
  136. .PP
  137. \fBTcl_FreeResult\fR is a macro that performs part of the work
  138. of \fBTcl_ResetResult\fR.
  139. It frees up the memory associated with \fIinterp\fR's result
  140. and sets \fIinterp->freeProc\fR to zero, but it doesn't
  141. change \fIinterp->result\fR or clear error state.
  142. \fBTcl_FreeResult\fR is most commonly used when a procedure
  143. is about to replace one result value with another.
  144.  
  145. .SH "SEE ALSO"
  146. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  147.  
  148. .SH KEYWORDS
  149. append, command, element, list, result, return value, interpreter
  150.